﻿/**
 * The SharedObject class lets you store data on the server and share data between multiple client applications
 * in real time. Shared objects can be temporary, or they can persist on the server after an application has
 * closed; you can consider shared objects as real-time data transfer devices. 
 * 
 * * Storing and sharing data on a server. A shared object can store data on the server for other clients to retrieve.
 * For example, you can open a remote shared object, such as a phone list, that is persistent on the server.
 * Whenever a client makes a change to the shared object, the revised data is available to all clients that are
 * currently connected to the object or that connect to it later. If the object is also persistent locally and a 
 * client changes the data while not connected to the server, the changes are copied to the remote shared object
 * the next time the client connects to the object. 
 * 
 * * Sharing data in real time. A shared object can share data among multiple clients in real time. For example, 
 * you can open a remote shared object that stores real-time data that is visible to all clients connected to the 
 * object, such as a list of users connected to a chat room. When a user enters or leaves the chat room, the object
 * is updated and all clients that are connected to the object see the revised list of chat-room users. 
 * 
 * * Every remote shared object is identified by a unique name and contains a list of name-value pairs, called 
 * properties, like any other ActionScript object. A name must be a unique string and a value can be any ActionScript
 * data type.
 * 
 * @author waneck
 */

package asc;

extern class SharedObject implements Dynamic
{
	static inline function __init__():Void untyped
	{
		__js__("asc.SharedObject = SharedObject");
	}
	
	/**
	 * A boolean value indicating whether the server periodically stores all persistent shared objects (true) or not
	 * (false). If autoCommit is false, the application must call SharedObject.commit() to save the shared object;
	 * otherwise, the data is lost.
	 * 
	 * This property is true by default. To override the default, specify the initial state by using the following
	 * configuration key in the Application.xml file, as shown in the following example:
	 */
	var autoCommit:Bool;
	
	/**
	 * Read-only; a boolean value indicating whether a persistent shared object has been modified since the last time 
	 * it was stored (true) or not (false). The SharedObject.commit()  method stores shared objects with an isDirty 
	 * property that is true.
	 * 
	 * This property is always false for nonpersistent shared objects. 
	 */
	var isDirty(default, null):Bool;
	
	/**
	 * Read-only; the name of a shared object.
	 */
	var name(default, null):String;
	
	/**
	 * An integer that indicates when the deleted properties of a shared object should be permanently deleted. You can
	 * use this property in a server-side script to resynchronize shared objects and to control when shared objects
	 * are deleted. The default value is infinity.
	 * 
	 * If the current revision number of the shared object minus the revision number of the deleted property is 
	 * greater than the value of SharedObject.resyncDepth, the property is deleted. Also, if a client connecting to
	 * this shared object has a client revision that, when added to the value of SharedObject.resyncDepth, is less
	 * than the value of the current revision on the server, all the current elements of the client shared object are
	 * deleted, the valid properties are sent to the client, and the client receives a “clear” message.
	 * 
	 * This method is useful when you add and delete many properties and you don’t want to send too many messages to
	 * the client. Suppose that a client is connected to a shared object that has 12 properties and then disconnects.
	 * After that client disconnects, other clients that are connected to the shared object delete 20 properties and
	 * add 10 properties. When the client reconnects, it could, for example, receive a delete message for the 10
	 * properties it previously had and then a change message on two properties. You can use SharedObject.resyncDepth 
	 * property to send a “clear” message, followed by a change message for two properties, which saves the client 
	 * from receiving 10 delete messages.
	 */
	var resyncDepth:Int;
	
	/**
	 * Read-only; the current version number of the shared object. Calls to the SharedObject.setProperty() method 
	 * on either the client or the server increment the value of the version  property.
	 */
	var version(default, null):Int;
	
	/**
	 * Deletes all the properties of a single shared object and sends a clear event to all clients that subscribe
	 * to a persistent shared object. The persistent data object is also removed from a persistent shared object. 
	 * 
	 * @return	Returns true if successful; otherwise, false. 
	 */
	function clear():Bool;
	
	/**
	 * Detaches a reference from a shared object. A call to the SharedObject.get() method returns a reference to a
	 * shared object instance. The reference is valid until the variable that holds the reference is no longer in use
	 * and the script is garbage collected. To destroy a reference immediately, you can call SharedObject.close().
	 * You can use SharedObject.close() when you no longer want to proxy a shared object. 
	 */
	function close():Void;
	
	/**
	 * Static; stores either a specific persistent shared object instance or all persistent shared object instances
	 * with an isDirty  property whose value is true. Use this method if the SharedObject.autoCommit property is
	 * false and you need to manage when a shared object is stored locally.
	 * 
	 * @param	?name	A string indicating the name of the persistent shared object instance to store. If no name 
	 * 					is specified, or if an empty string is passed, all persistent shared objects are stored. 
	 * 					This parameter is optional. 
	 * @return	A boolean value indicating success (true) or failure (false).
	 */
	static function commit(?name:String):Bool;
	
	/**
	 * Saves the current state of a persistent shared object. Invokes the SharedObject.onStatus() handler and passes
	 * it an object that contains information about the success or failure of the call.
	 * @return	A boolean value of true if successful; otherwise, false.
	 */
	function flush():Bool;
	
	/**
	 * Static; creates a shared object or returns a reference to an existing shared object. To perform any operation 
	 * on a shared object, the server-side script must get a reference to the shared object by using the
	 * SharedObject.get() method. If the requested object is not found, a new instance is created.
	 * @param	name			Name of the shared object instance to return.
	 * @param	persistence		A boolean value: true for a persistent shared object; false for a nonpersistent 
	 * 							shared object. If no value is specified, the default value is false.
	 * @param	?netConnection	A NetConnection object that represents a connection to an application instance. 
	 * 							You can pass this parameter to get a reference to a shared object on another server
	 * 							or a shared object that is owned by another application instance. All update
	 * 							notifications for the shared object specified by the name parameter are proxied to
	 * 							this instance, and the remote instance notifies the local instance when a persistent
	 * 							shared object changes. The NetConnection object that is used as the netConnection
	 * 							parameter does not need to be connected when you call SharedObject.get(). The server
	 * 							connects to the remote shared object when the NetConnection state changes to connected.
	 * 							This parameter is optional.
	 * @return	A reference to an instance of the SharedObject class.
	 */
	static function get(name:String, persistence:Bool, ?netConnection:asc.net.NetConnection):SharedObject;
	
	/**
	 * Retrieves the value of a named property in a shared object. The returned value is a copy associated with the
	 * property, and any changes made to the returned value do not update the shared object. To update a property,
	 * use the SharedObject.setProperty() method. 
	 * @param	name	A string indicating the name of a property in a shared object.
	 * @return	The value of a SharedObject property. If the property doesn’t exist, returns null.
	 */
	function getProperty(name:String):Dynamic;
	
	/**
	 * Enumerates all the property names for a given shared object.
	 * 
	 * @return	An array of strings that contain all the property names of a shared object.
	 */
	function getPropertyNames():Array<String>;
	
	/**
	 * Locks a shared object. This method gives the server-side script exclusive access to the shared object; when the 
	 * SharedObject.unlock()  method is called, all changes are batched and one update message is sent through the
	 * SharedObject.onSync() handler to all the clients that subscribe to this shared object. If you nest the
	 * SharedObject.lock() and SharedObject.unlock()  methods, make sure that there is an unlock() method for every
	 * lock() method; otherwise, clients are blocked from accessing the shared object.
	 * 
	 * You cannot use the SharedObject.lock() method on proxied shared objects.
	 * @return	An integer indicating the lock count: 0 or greater indicates success; -1 indicates failure.
	 * 			For proxied shared objects, always returns -1.
	 */
	function lock():Int;
	
	/**
	 * Delivers all change events to a subscribing client as a single message.
	 * 
	 * In a server-side script, you can call the SharedObject.setProperty() method to update multiple shared object
	 * properties between a call to the lock() and unlock() methods. All subscribing clients receive a change event
	 * notification through the SharedObject.onSync() handler. However, because the server may collapse multiple
	 * messages to optimize bandwidth, the change event notifications may not be sent in the same order as they were
	 * in the code.
	 * 
	 * Use the mark() method to execute code after all the properties in a set have been updated. You can call the
	 * handlerName parameter passed to the mark() method, knowing that all property changes before the mark() call
	 * have been updated. 
	 * @param	handlerName	Calls the specified handler on the client-side SharedObject instance. For example, if the
	 * 				handlerName parameter is onChange, the client invokes the SharedObject.onChange()  handler with 
	 * 				all the p1, ...,pN parameters. 
	 * @param	?p1...?p7	Parameters of any ActionScript type, including references to other ActionScript objects.
	 * 				Parameters are passed to handlerName when it is executed on the client.
	 * @return	A boolean value. Returns true if the message can be dispatched to the client; otherwise, false.
	 */
	function mark(handlerName:String, ?p1:Dynamic, ?p2:Dynamic, ?p3:Dynamic, ?p4:Dynamic, ?p5:Dynamic, ?p6:Dynamic, ?p7:Dynamic):Bool;
	
	/**
	 * Causes the server to remove all deleted properties that are older than the specified version. Although you
	 * can also accomplish this task by setting the SharedObject.resyncDepth  property, the purge() method gives
	 * the script more control over which properties to delete.
	 * 
	 * @param	version	A number indicating the version. All deleted data that is older than this version is removed.
	 * 
	 * @return	Bool
	 */
	function purge(version:Int):Bool;
	
	/**
	 * Executes a method in a client-side script. You can use SharedObject.send() to asynchronously execute 
	 * a method on all the Flash clients subscribing to a shared object. The server does not receive any notification
	 * from the client on the success, failure, or return value in response to this message.
	 * 
	 * @param	methodName	A string indicating the name of a method on a client-side shared object. For example, 
	 * 				if you specify "doSomething", the client must invoke the SharedObject.doSomething()  method, 
	 * 				with all the p1, ..., pN parameters.
	 * @param	?p1...?p7	Parameters of any type, including references to other objects. These parameters are
	 * 				passed to the specified methodName  on the client.
	 * @return	A boolean value of true if the message was sent to the client; otherwise, false. 
	 */
	function send(methodName:String, ?p1:Dynamic, ?p2:Dynamic, ?p3:Dynamic, ?p4:Dynamic, ?p5:Dynamic, ?p6:Dynamic, ?p7:Dynamic):Bool;
	
	/**
	 * Updates the value of a property in a shared object.
	 * 
	 * The name parameter on the server side is the same as an attribute of the data property on the client side.
	 * For example, the following two lines of code are equivalent; the first line is Server-Side ActionScript
	 * and the second is client-side ActionScript:
	 * 		so.setProperty(nameVal, "foo"); 
	 * 		clientSO.data[nameVal] = "foo";
	 * 
	 * @param	name	The name of the property in the shared object. 
	 * @param	value	An ActionScript object associated with the property, or null to delete the property.
	 */
	function setProperty(name:String, value:Dynamic):Void;
	
	/**
	 * Returns the total number of valid properties in a shared object.
	 * @return
	 */
	function size():Int;
	
	/**
	 * Allows other clients to update the shared object. A call to this method also causes the server to commit all
	 * changes made after the SharedObject.lock() method is called and sends an update message to all clients.
	 * 
	 * You cannot call the SharedObject.unlock() method on proxied shared objects.
	 * @return	An integer indicating the lock count: 0 or greater if successful; -1 otherwise. 
	 * 			For proxied shared objects, this method always returns -1.
	 */
	function unlock():Int;
	
	
	//dynamic function handlerName()
	
	/**
	 * Invoked when errors, warnings, and status messages associated with either a local instance of a shared object 
	 * or a persistent shared object occur. 
	 * 
	 * @param	info	An information object.
	 */
	dynamic function onStatus(infoObj: { level:String, code:String } ):Void;
	
	/**
	 * Invoked when a shared object changes. Use the onSync()  handler to define a function that handles changes made
	 * to a shared object by subscribers.
	 * 
	 * For proxied shared objects, defines the function to get the status of changes made by the server and other
	 * subscribers.
	 * 
	 * @see		asc.enums.SharedObjectChange
	 */
	dynamic function onSync(list:Array<{code:String, name:String, oldValue:String}>):Void;

	public function new():Void;
	
}